"In pre beta-4 GX, the page passed to gxRenderPage could be easily dis-assembled into its component parts with GXGetPictureParts. Since Beta-4 only jobs spooled from a new-API application can be analyzed. From old-API apps, the picture only contains one part, usually a rectangle."
At about beta 4, there was a new type of gxShape introduced, the "QuickDraw shape." This shape is explained in the GX Printing book (page 4-18) and in the GX Extensions and Drivers book (page 3-6). The text from those references appears at the end of this message. When you print from an old app, these shapes are created by default. They are essentially the old PICT data in a GX shape wrapper. Two of the reasons thay we do things this way is that it decreases spooling time, and since the PICT is converted as needed at rendering time, it's easier on the imaging engine memory-wise.
You can convert the shape into a gxPicture shape by calling:
GXSetShapeType(aQDShape, gxPictureType);
You can also disable the QD shape generation at spool time by overriding GXFetchTaggedData and looking for a 'pcfg' resource being loaded. If you clear the high bit of the data being returned, the application's data will be written into the spool file without using the QuickDraw shape. However, this approach is not recommended, since we added the QD shape for very good reasons, and even if you turn it off during spooling, you'll still need to deal with the case of a redirected file containing QD shapes.
When will QuickDraw GX translate the “QuickDraw shape”??
QuickDraw GX will do the conversions from the QuickDraw data to QDGX shapes in the default implementations of gxPostScriptProcessShape for PostScript drivers, and gxImagePage for vector and raster drivers.
So, if your printer driver or printing extension needs to convert the shape, doing so in gxDespoolPage or gxRenderPage would make sense. (gxRenderPage sends gxImagePage, and for PostScript drivers gxRenderPage sends gxPostScriptProcessShape.)
If simply parsing the “QuickDraw shape” will give you enough information, then you should not convert the shape to a gxPicture. Rather, use the code on this CD entitled TranslateQDShape.c to parse the shape, and leave the original intact.
Inside Macintosh information about “QuickDraw shapes.”
[Inside Macintosh QuickDraw GX Printing, page 3-5]
Spooling Translated QuickDraw Data in Print Files
When spooling a file that contains QuickDraw drawing commands, QuickDraw GX by default stores untranslated QuickDraw data in the print file. When the print file is despooled and imaged, QuickDraw GX then converts the data to QuickDraw GX shapes and prints them. If you want to force QuickDraw GX to translate QuickDraw data to QuickDraw GX shapes before spooling, you can override the GXFetchTaggedData message that QuickDraw GX sends at spooling time to fetch resource data of type 'pcfg'. Your override should forward the message, and then clear the highest-order bit of the data that is returned from the message. If the data’s highest-order bit is cleared, QuickDraw GX translates and stores the data in the print file as QuickDraw GX shapes. For more information on QuickDraw data in print files, see the discussion of the 'pict' tag object in the advanced printing features chapter of Inside Macintosh: QuickDraw GX Printing.
[Inside Macintosh QuickDraw GX Printing, page 3-6]
Despooling Print Files Containing QuickDraw Picture Data
When a document containing QuickDraw imaging commands is spooled, QuickDraw GX by default saves the QuickDraw data for each page in a tag object of tag type 'pict' attached to a rectangle shape. If you examine the contents of a despooled file, note that the presence of a rectangle shape with such an attached tag object indicates the presence of QuickDraw picture data. For more information, see the discussion of the 'pict' tag object in the advanced printing features chapter of Inside Macintosh: QuickDraw GX Printing.
[Inside Macintosh QuickDraw GX Printing, page 4-18]
QuickDraw Picture Synonym
When QuickDraw GX spools a document containing QuickDraw imaging commands, it creates and flattens, for each page, a QuickDraw GX rectangle shape with an attached tag object of tag type 'pict' (the QuickDraw GX constant for that tag type is gxQuickDrawPictTag). The tag object contains information that specifies the characteristics and location of a file containing QuickDraw picture data for that page.
When QuickDraw GX subsequently despools the file, it (or the printer driver) uses the QuickDraw GX Translator to convert the QuickDraw picture data into a QuickDraw GX picture shape before printing it. The tag object contains a gxQuickDrawPict structure:
struct gxQuickDrawPict {
gxTranslationOptions options;
Rect srcRect;
Point styleStretch;
unsigned long dataLength;
struct gxBitmapDataSourceAlias alias;
};
Field descriptions
options - The translation options to be used by the QuickDraw GX Translator when converting the QuickDraw data.
srcRect - The source rectangle for the translation, in QuickDraw coordinates. It controls scaling of the image. This rectangle is the QuickDraw picture frame that bounds the QuickDraw data.
styleStretch - The scale factor (both horizontal and vertical) to apply to certain items, such as dashes, in QuickDraw picture comments.
dataLength - The length of the QuickDraw picture data, in bytes.
alias - A structure that defines the location of the file containing the QuickDraw data, and the offset within the file to that data.
The QuickDraw GX rectangle shape that the tag object is attached to specifies the destination bounding rectangle for drawing the QuickDraw data (in QuickDraw coordinates). The relative sizes of the source rectangle and destination rectangle control the scaling of the image when it is translated.
The QuickDraw GX Translator is described in the environment chapter of Inside Macintosh: QuickDraw GX Environment and Utilities. Tag objects are described in the tag objects chapter of Inside Macintosh: QuickDraw GX Objects. The gxBitmapDataSourceAlias structure is described in the bitmap shapes chapter of Inside Macintosh: QuickDraw GX Graphics.
[Inside Macintosh QuickDraw GX Graphics, page 5-65]
Bitmap Data Source Alias Structure
QuickDraw GX provides the bitmap data source alias structure to allow you to specify file information for disk-based pixel images.
struct gxBitmapDataSourceAlias {
unsigned long fileOffset;
unsigned long aliasRecordSize;
unsigned char aliasRecord[gxAnyNumber];
};
Field descriptions
fileOffset - The offset in bytes from the beginning of the file to the first pixel value of the pixel image.
aliasRecordSize - The size in bytes of the alias record.
aliasRecord - A Macintosh Alias Manager alias record specifying the file containing the pixel image.
For an example of a bitmap with a disk-based pixel image, see “Creating Bitmaps With Disk-Based Pixel Images” beginning on page 5-44.
[Inside Macintosh QuickDraw GX Graphics, page 5-44]
Creating Bitmaps With Disk-Based Pixel Images
QuickDraw GX allows you to store the pixel image of a bitmap shapes in a disk file. To create this type of bitmap, you specify a predefined constant for the image field of the bitmap’s geometry:
You specify the file that contains the pixel image using the bitmap data source alias structure, which is defined by the gxBitmapDataSourceAlias data type:
struct gxBitmapDataSourceAlias {
unsigned long fileOffset; /* offset (in bytes) to image */
unsigned long aliasRecordSize; /* size of alias record */
unsigned char aliasRecord[gxAnyNumber];/* alias record */
};
To use this data type, you need to declare a variable to hold the structure:
gxBitmapDataSourceAlias anAlias;
Then, you need to set the three fields of the structure:
• the aliasRecord field should contain a Macintosh Alias Manager alias record specifying the file containing the pixel image
• the aliasRecordSize field should specify the size in bytes of the alias record
• the fileOffset field should specify the offset in bytes from the beginning of the data fork of the file to the first pixel value of the pixel image
Once you’ve created the bitmap data source alias structure, you create a tag object to encapsulate the structure, using the call
Now the disk-based bitmap is completely initialized. You can use most bitmap-related functions with this bitmap, but there are bitmap-related functions you cannot use. In particular, you cannot call the GXSetBitmapParts, GXSetShapePixel, GXNewViewDevice, or GXSetViewDeviceBitmap functions, as these functions would require QuickDraw GX to write to the file.
For more information about alias records, see the chapter “Alias Manager” of Inside Macintosh: Files.
For more information about tags and the GXNewTag function, see the chapter “Tag Objects” of Inside Macintosh: QuickDraw GX Objects. For information about the GXSetShapeTags function, see the chapter “Shape Objects” in that book.
